home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / systems / atari / birkhahn-metafont-packed-disks / mf27-2_2e-disk2.zoo / doc.lzh / EXARG.DOC < prev    next >
Text File  |  1990-12-31  |  19KB  |  453 lines
  1. GEMDOS EXTENDED ARGUMENT (ARGV) SPECIFICATION
  2.  
  3. Introduction
  4.  
  5. The Pexec() function of GEMDOS allows a program to pass to a child
  6. process a command line up to 125 characters long, with arguments
  7. separated by spaces.  No provision is made in GEMDOS for the child to
  8. know its own name.  This makes it difficult for C programs to correctly
  9. fill in argv[0], the standard place where a C program finds the command
  10. which invoked it.  Because the command line arguments are separated by
  11. spaces, it is difficult to pass an argument with an embedded space.
  12. This document will specify a method of passing arguments which allows
  13. arbitrary argument length, embedded spaces, and support for argv[0].
  14.  
  15. Standard Argument Passing
  16.  
  17. The Pexec Cookbook specifies how to use Pexec() to launch a child
  18. process, passing a command tail (argument string) and an environment.
  19. Before getting into the extended argument scheme, let's review how
  20. arguments are normally passed to a child.
  21.  
  22. A parent process builds a command line into an argument string - a null
  23. terminated string whose first byte contains the length of the rest of
  24. the string - and its address is passed as one of the arguments to
  25. Pexec().  GEMDOS copies this argument string to the basepage which it
  26. creates for the child.  Thus the parent is responsible for gathering
  27. all the child's arguments into one string.  This is normally handled by
  28. a library exec() function.  The child is responsible for parsing the
  29. string of space-separated arguments back into an array of strings.
  30. This parsing is normally handled by the child's startup code.
  31.  
  32. Evolution
  33.  
  34. Several methods of bypassing the limits imposed by Pexec() have been
  35. used by GEMDOS programs.  Some allow a user to specify a file on the
  36. command line which contains the rest of the arguments.  Others get a
  37. pointer to the arguments, or the arguments themselves, from the
  38. environment string.  Most MS-DOS programs use a command file for the
  39. extra arguments.  This can be inconvenient for a user, cluttering the
  40. file system with command files, and making the operation of batch files
  41. and makefiles more confusing.
  42.  
  43. Several "standards" have arisen on the ST which use the environment to
  44. pass arguments.  While more convenient than command files, these
  45. standards have other problems.  Some rely on sharing memory between
  46. parent and child processes.  Some take advantage of undocumented
  47. features of the operating system to get argv[0].  Others give the
  48. child process no way to validate that the arguments it finds are
  49. intended for it.
  50.  
  51. Rationale
  52.  
  53. In order to pass more than the standard 125 characters worth of
  54. arguments to a child, or to let the child find its name, the parent
  55. must place the extra information in a place where the child can access
  56. it safely and legally.  The most convenient place is in the child's
  57. environment string.  An environment string is a series of
  58. null-terminated strings of the format "VARIABLE=value" (e.g.
  59. PATH=c:\bin,c:\etc, or ShellP=YES).   The last null-terminated string
  60. in the environment is followed by a zero byte, thus two consecutive
  61. nulls indicates the end of the environment.   The environment is
  62. allocated for the child by GEMDOS, it is owned by the child, and its
  63. contents can be specified by the parent.
  64.  
  65. The child must have some way of knowing that the arguments which
  66. it finds in its environment are intended for it.  The child may have
  67. been invoked by a parent which does not conform to this specification.
  68. Such a parent would leave _its_ arguments in the environment, and could
  69. pass that environment on to the child.  The child would mistakenly
  70. interpret its parent's arguments as its own.
  71.  
  72. Placing arguments in the environment passed to the child gets around
  73. all of the command line limits of the standard Pexec() command tail.
  74. Because there is no limit on the length of the environment, arbitrary
  75. length arguments are supported.  Arguments placed in the environment
  76. are null terminated, so they may contain spaces.  A parent can also
  77. place the name of the command with which it invokes the child in the
  78. child's environment, providing support for argv[0].  Validation of the
  79. extended arguments can be placed in the standard Pexec() command line,
  80. by assigning a special meaning to an invalid length byte.
  81.  
  82. The GEMDOS Extended Argument Specification
  83.  
  84. This specification uses the convention that the presence of an
  85. environment variable named ARGV (all upper case) indicates that extended
  86. arguments are being passed to the child in its environment.  This means
  87. that ARGV is a "boolean" environment variable.  For the purpose of this
  88. specification, its value is not significant, but its presence indicates
  89. that the strings following it are the arguments for the child.
  90. Implementations of this specification are free to give the ARGV
  91. environment variable any value.  The ARGV environment variable must be
  92. the last one in the environment passed to the child, so that the child
  93. can truncate its environment at that point, and treat everything before
  94. the ARGV as environment, and everything after it as arguments.
  95.  
  96. The first argument to the child (argv[0]) is the first string in the
  97. environment after the ARGV variable.  This argument is the "pathname"
  98. parameter passed by the parent to Pexec().  The remaining arguments are
  99. those that the child would normally find in the command tail in its
  100. basepage.  Even if all of the arguments would normally fit in a child's
  101. command tail, the parent should set up the arguments in the environment
  102. to take advantage of the benefits of this extended argument scheme.
  103.  
  104. As many arguments as will fit in the command tail will be passed there
  105. as well as in the environment, to support non-conforming programs.  As
  106. a flag that arguments are also in the environment, the length byte of
  107. the command tail will be 127 (hex 7f).  Non-conforming programs should
  108. not have a problem with this length byte, because it is longer than the
  109. maximum 125 bytes allowed by Pexec().
  110.  
  111. As an aside, the Pexec Cookbook erroneously implies that a command line
  112. can be 126 or 127 characters long.  In fact, GEMDOS only copies to the
  113. child's basepage up to 125 bytes, or until it encounters a null, from
  114. the argument string passed to Pexec().  It ignores the length byte,
  115. placing a null at the same place it found one or at the 126th byte if
  116. no null is found.  This has several implications: the length byte is
  117. not validated by GEMDOS (necessitating validation in the child's
  118. startup code, but also making this extended argument spec possible),
  119. and the null terminator _can_ be located after the end of the real
  120. command tail (the Desktop places a CR character after the command tail
  121. and before the null).  The ARGSTART.S startup code listing below
  122. demonstrates how to correctly validate and parse a GEMDOS command tail.
  123.  
  124. A child which finds an ARGV environment variable can use the command
  125. tail length byte value of 127 to validate that the arguments following
  126. the variable are valid, and not just left over from a non-conforming
  127. parent which left its own ARGV arguments in the environment.
  128.  
  129. Because the strings in the environment following an ARGV variable are
  130. not environment variables, a child should truncate its own environment
  131. at the ARGV variable by changing the 'A' to a null.
  132.  
  133. Implementation: Parental Responsibilities
  134.  
  135. To pass arguments in the environment, a parent must create an
  136. environment string for the child.  This can be achieved by first
  137. allocating as much space as is used in the parent's own environment,
  138. plus enough room for the ARGV variable and the arguments to the child,
  139. and then copying the parent's environment to the newly allocated area.
  140. Next, the ARGV variable must be appended, since it must be the last
  141. variable in the child's environment string.  Following the ARGV variable
  142. is the null-terminated pathname of the child as passed to Pexec(), then
  143. the null-terminated arguments to the child, followed by a final null
  144. byte indicating the end of the environment.
  145.  
  146. After setting up the arguments in the environment, the parent must
  147. place as many arguments as it can fit in the command tail it passes
  148. to Pexec().  This way, a child which does not conform to this
  149. specification can still get arguments from the command tail in its
  150. basepage.  When placing arguments in the environment, the parent must
  151. set the first (length) byte of the command tail to 127 (hex 7f),
  152. validating the arguments in the environment.
  153.  
  154. Here is an example execv() library routine in C.  It uses three local
  155. utility routines, e_strlen(), e_strcpy(), and str0cpy() for getting
  156. environment size and copying strings into the environment created for
  157. the child.
  158.  
  159.  
  160. /* EXECV.C - example execv() library routine
  161.  * ================================================================
  162.  * 890910 kbad
  163.  */
  164.  
  165. long Malloc( long nbytes );
  166. long Pexec( short mode, char *filename, char *tail, char *env );
  167. long Mfree( void *address );
  168.  
  169. /* Return the total length of the characters and null terminators in
  170.  *   an array of strings.
  171.  * `strings' is an array of pointers to strings, with a null pointer
  172.  *   as the last element.
  173.  */
  174. static long
  175. e_strlen( char *strings[] )
  176. {
  177.     char    *pstring;
  178.     long    length = 0;
  179.  
  180.     while( *strings != 0 ) {        /* Until reaching null pointer,    */
  181.     pstring = *strings++;        /* get a string pointer,        */
  182.     do {                /* find the length of this string,  */
  183.         ++length;            /* using do-while to count the    */
  184.     } while( *pstring++ != 0 ); /* null terminator.            */
  185.     }
  186.     return length;            /* Return total length of all strings */
  187. }
  188.  
  189. /* Copy a string, including the null terminator, and return a pointer
  190.  * to the end of the destination string.
  191.  */
  192. static char *
  193. str0cpy( char *dest, char *source )
  194. {
  195.     do { /* use do-while to include null terminator */
  196.     *dest++ = *source;
  197.     } while( *source++ != 0 );
  198.     return dest;
  199. }
  200.  
  201. /* Copy an array of strings into an environment string, and return a pointer
  202.  * to the end of the environment string.
  203.  * `strings' is an array of pointers to strings with a null pointer
  204.  *   as the last element.
  205.  * `envstring' points to the environment string.
  206.  */
  207. static char *
  208. e_strcpy( char *envstring, char *strings[] )
  209. {
  210.     while( *strings != 0 ) {
  211.     envstring = str0cpy( envstring, *strings );
  212.     ++strings;
  213.     }
  214.     return envstring;            /* Return end of environment string */
  215. }
  216.  
  217.  
  218. /* Run a program, passing it arguments according to the
  219.  * GEMDOS Extended Argument Spec.
  220.  *
  221.  * `childname' is the relative path\filename of the child to execute.
  222.  * `args' is an array of pointers to strings to be used as arguments
  223.  *   to the child.  The last array element must be a null pointer.
  224.  * `environ' is a global array of pointers to strings
  225.  *   which make up the caller's environment.
  226.  */
  227. long
  228. execv( char *childname, char *args[] )
  229. {
  230.     long    envsize, ret;
  231.     char    *parg, *penvargs, *childenv, *pchildenv;
  232.     short    lentail;
  233.     char    argch, tail[128], *ptail;
  234. static  char    argvar[] = "ARGV=";
  235. extern  char    *environ[];
  236.  
  237. /*
  238.  * Find out how much memory we'll need for the child's environment
  239.  */
  240.     envsize = e_strlen( environ );    /* length of environment    */
  241.     envsize += e_strlen( args );    /* plus command tail args    */
  242. /* plus length of argv[0] */
  243.     parg = childname;
  244.     do { /* use do-while to include null terminator */
  245.     ++envsize;
  246.     } while( *parg++ != 0 );
  247. /* plus length of ARGV environment variable and final null */
  248.     envsize += 7;
  249.     envsize += envsize & 1; /* even # of bytes */
  250. /*
  251.  * Allocate and fill in the child's environment
  252.  */
  253.     ret = Malloc( envsize );
  254.     if( ret < 0 )
  255.     return ret; /* Malloc error */
  256.     childenv = (char *)ret;
  257.     pchildenv = e_strcpy( childenv, environ );     /* copy caller environment */
  258.     pchildenv = str0cpy( pchildenv, argvar );     /* append ARGV variable */
  259.     pchildenv = str0cpy( pchildenv, childname ); /* append argv[0] */
  260.     penvargs = pchildenv;             /* save start of args */
  261.     pchildenv = e_strcpy( pchildenv, args );     /* append args */
  262.     *pchildenv = 0;                 /* terminate environment */
  263. /* put as much in the command tail as will fit */
  264.     lentail = 0;
  265.     ptail = &tail[1];
  266.     while( (lentail < 126) && (penvargs < pchildenv) ) {
  267.     argch = *penvargs++;
  268.     if( argch == 0 ) {
  269.         *ptail++ = ' ';
  270.     } else {
  271.         *ptail++ = argch;
  272.     }
  273.     }
  274. /* terminate command tail and validate ARGV */
  275.     *ptail = 0;
  276.     tail[0] = 127;
  277. /*
  278.  * Execute child, returning the return code from Pexec()
  279.  */
  280.     ret = Pexec( 0, childname, tail, childenv );
  281.     Mfree( childenv );
  282.     return ret;
  283. }
  284. /* End of execv() example code */
  285.  
  286.  
  287. Implementation: Prenatal Responsibilities
  288.  
  289. A program's startup code must handle getting extended arguments out of
  290. the environment.  The startup code should get the basepage pointer off
  291. the stack, then get the environment pointer from the basepage, and
  292. search the environment for "ARGV=".  If "ARGV=" is found, the command
  293. line length byte in the basepage is checked.  If the command line
  294. length byte is 127, then the arguments in the environment are valid.
  295. The first argument begins after the first null following the "ARGV=".
  296. It is important not to assume that the null follows immediately after
  297. the "ARGV=", because some implementations may assign a value to the
  298. ARGV environment variable.  After setting up an array of pointers to the
  299. arguments, the startup code should set the 'A' of the "ARGV" variable
  300. to null, thus separating the environment from the argument strings
  301. (remember: a double null terminates the environment).
  302.  
  303. Here is some example C startup code which shows how a child could
  304. look for arguments in its environment:
  305.  
  306. * ARGSTART.S - example C startup code
  307. * using GEMDOS Extended Argument Specification
  308. * ================================================================
  309. * 890910 kbad
  310.  
  311. .globl        _main        ; external, C entry point
  312. .globl        _argv0        ; external, name used for argv[0] if no ARGV
  313. .globl        _stksize    ; external, size of application stack
  314. .globl        _basepage    ; allocated here, -> program's basepage
  315. .globl        _environ    ; allocated here, -> envp[]
  316. .globl        _argvecs    ; allocated here, -> argv[]
  317. .globl        _stklimit    ; allocated here, -> lower limit of stack
  318. .BSS
  319. _basepage:    ds.l    1
  320. _environ:    ds.l    1
  321. _argvecs:    ds.l    1
  322. _stklimit:    ds.l    1
  323. .TEXT
  324. _start:
  325.     move.l    4(sp),a5    ; get basepage
  326.     move.l    a5,_basepage    ; save it
  327.     move.l    24(a5),a0    ; bss base
  328.     add.l    28(a5),a0    ; plus bss size = envp[] base
  329.     move.l    a0,_environ    ; save start of envp[]
  330.     move.l    a0,a1        ; start of env/arg vectors
  331.     move.l    44(a5),a2    ; basepage environment pointer
  332.     tst.b    (a2)        ; empty environment?
  333.     beq.s    nargv        ; yes, no envp[]
  334.  
  335.     lea.l    (sp),a4        ; use dummy return pc on stack for ARGV test
  336. * --- fill in the envp[] array
  337. nxenv:    move.l    a2,(a1)+    ; envp[n]
  338.     move.l    a2,a3
  339. nxen1:    tst.b    (a2)+
  340.     bne.s    nxen1        ; get the end of this variable
  341.     tst.b    (a2)        ; end of env?
  342.     beq.s    xenv
  343. * --- check for ARGV
  344.     move.b    (a3)+,-(a4)    ; get 1st 4 bytes of this var
  345.     move.b    (a3)+,-(a4)
  346.     move.b    (a3)+,-(a4)
  347.     move.b    (a3)+,-(a4)
  348.     cmp.l    #'VGRA',(a4)+    ; is it ARGV?
  349.     bne.s    nxenv
  350.     cmp.b    #'=',(a3)    ; is it ARGV=?
  351.     bne.s    nxenv
  352.     clr.b    -4(a3)        ; ARGV marks the end of our environment
  353.     cmp.b    #127,$80(a5)    ; command line validation?
  354.     bne.s    nargv        ; nope... and we're done with the env.
  355. * --- got an ARGV=, create argv[] array
  356.     clr.l    (a1)+        ; terminate envp[]
  357.     move.l    a1,_argvecs    ; save base of argv[]
  358. nxarg:    move.l    a2,(a1)+    ; argv[n]
  359. nxar1:    tst.b    (a2)+
  360.     bne.s    nxar1
  361.     tst.b    (a2)
  362.     bne.s    nxarg
  363. * --- end of environment
  364. xenv:    move.l    _argvecs,d0    ; if we got an argv[]
  365.     bne.s    argok        ; don't parse command tail
  366. * --- No ARGV, parse the command tail
  367. * NOTE: This code parses the command tail IN PLACE.  This can cause problems
  368. *       because the default DTA set up by GEMDOS for a program is located
  369. *       in the command tail part of the basepage.  You should use Fsetdta()
  370. *       to set up your own DTA before performing any operations which could
  371. *       use the DTA if you want to preserve the arguments in the command tail.
  372. nargv:    clr.l    (a1)+        ; terminate envp[]
  373.     move.l    a1,_argvecs    ; base of argv[]
  374.     move.l    #_argv0,(a1)+    ; default name for argv[0]
  375.     lea    128(a5),a2    ; command tail
  376.     move.b    (a2)+,d2    ; length byte
  377.     ext    d2
  378.     moveq    #125,d1        ; validate length
  379.     cmp    d1,d2
  380.     bcs.s    valen
  381.     move    d1,d2        ; if invalid length, copy all of tail
  382. valen:    clr.b    0(a2,d2)    ; null tail because desktop inserts <cr>
  383.     moveq    #' ',d1        ; space terminator
  384. get1:    move.b    (a2)+,d2    ; null byte?
  385.     beq.s    argok        ; if so, we're done
  386.     cmp.b    d1,d2        ; strip leading spaces
  387.     beq.s    get1
  388.     subq    #1,a2        ; unstrip start char
  389.     move.l    a2,(a1)+    ; and store that arg
  390. get2:    move.b    (a2)+,d2    ; next char
  391.     beq.s    argok        ; if null, we're done
  392.     cmp.b    d1,d2        ; if not space...
  393.     bne.s    get2        ; keep looking
  394.     clr.b    -1(a2)        ; terminate argv[argc] in the command tail
  395.     bra.s    get1        ; get next arg
  396. argok:    clr.l    (a1)+        ; terminate argv[]
  397. * --- allocate stack
  398.     move.l    a1,_stklimit    ; end of env/arg vectors is stack limit
  399.     add.l    _stksize,a1    ; allocate _stksize bytes of stack
  400.     move.l    a1,sp        ; set initial stack pointer
  401. * --- release unused memory
  402.     sub.l    a5,a1        ; size to keep
  403.     move.l    a1,-(sp)
  404.     move.l    a5,-(sp)    ; base of block to shrink
  405.     pea    $4a0000        ; Mshrink fn code + junk word of 0
  406.     trap    #1
  407.     lea    12(sp),sp    ; pop args
  408. *
  409. * Everything beyond here depends on implementation.
  410. * At this point, _environ points to envp[], _argvecs points to argv[],
  411. * and _stklimit points to the end of the argv array.  Thus argc can
  412. * be calculated as ((_stklimit-_argvecs)/4)-1.
  413. * _main could be invoked as follows:
  414. *
  415.     move.l    a5,-(sp)    ; basepage
  416.     move.l    _environ,-(sp)    ; envp[]
  417.     move.l    _argvecs,-(sp)    ; argv[]
  418.     move.l    _stklimit,d0    ; 4 bytes past end of argv[]
  419.     sub.l    (sp),d0        ; (argc+1) * sizeof( char * )
  420.     asr.l    #2,d0        ; argc+1
  421.     subq    #1,d0        ; argc
  422.     move    d0,-(sp)
  423.     jsr    _main        ; call mainline
  424.     lea    14(sp),sp    ; pop args
  425.  
  426.  
  427. A Final Note
  428.  
  429. This specification was formulated with careful deliberation, and with
  430. input from several companies and developers who have created
  431. development tools for GEMDOS.  The Mark Williams extended argument
  432. passing scheme was the main influence for this specification, because
  433. it has been in use, and supported by Mark Williams and other companies
  434. for several years.  This specification is very similar to the Mark
  435. Williams scheme, with the following important exceptions:
  436.  
  437. 1) Under the specification, the arguments after the ARGV environment
  438. variable may be validated by checking the command tail length byte.
  439. The Mark Williams execve() library function uses the command tail
  440. length byte as a telltale, but it is not checked by the crts0 startup
  441. code.  This validation is important for the reasons mentioned in the
  442. Rationale section above.
  443.  
  444. 2) The specification allows the ARGV environment variable to take on any
  445. value.  Mark Williams uses the value of ARGV as an iovector, which is
  446. described in the Mark Williams documentation.  The iovector should no
  447. longer be needed, as its primary purpose was to simplify the MWC
  448. implementation of the C library function isatty().
  449.  
  450. 3) Some versions of the MWC startup code do not require the ARGV= to
  451. have an `='.  Because ARGV is an actual environment variable in the
  452. specification, the equals character is required.
  453.